This document describes the ZoneRanger application, and is divided into the following sections:
Beta Version
Background Information
About ZoneRanger
Overview Window
Zone Window
Apple Menu
File Menu
Edit Menu
Zones Menu
Configure Menu
Special Menu
Help Menu
Hilite Submenu
Shortcuts
System Requirements
Known Limitations
Known Bugs
Copyright Notice
Source Code
Special Thanks
Comments and Suggestions
The reader is encouraged to read the entire document; if, however, one wants to get off to a quick start, one should read from the System Requirements section to the end of the document.
B E T A V E R S I O N
This is a beta version of the ZoneRanger application. If you find any bugs with the program, or have any comments or suggestions you would like to make, please send them to the address listed at the end of this document.
B A C K G R O U N D I N F O R M A T I O N
Each process on the Macintosh is associated with a heap zone, out of which the Memory Manager allocates memory blocks on behalf of the process. A heap zone contains a zone header followed by a series of memory blocks, each of which contains a block header followed by the contents of the block. A block header contains the size, type, and attributes of the block.
A block type is either relocatable, non-relocatable, or free. A relocatable block is one that the Memory Manager can move around the heap zone as needed, and contains the data that is referenced by a handle. A non-relocatable block is one that cannot move around the heap zone, and contains the data that is referenced by a pointer. A free block is unallocated, and the contents of the block are undefined. For the sake of simplicity, we shall refer to relocatable blocks as handles and non-relocatable blocks as pointers.
There are three block attributes, and they apply only to relocatable blocks: locked, purgeable, and resource. If a relocatable block has the locked attribute set, then it cannot be moved around the heap zone. If a relocatable block has the purgeable attribute set, then it can be converted to a free block if necessary. If a relocatable block has the resource attribute set, then it contains the data from a resource. For the sake of simplicity, we shall refer to these types of blocks as locked handles, purgeable handles, and resource handles, respectively.
The reader is referred to the "Memory" volume of "Inside Macintosh" for more detailed information about the structure of heap zones and memory blocks.
A B O U T Z O N E R A N G E R
ZoneRanger provides detailed information about each heap zone that is currently active on the Macintosh. This information includes both the counts and total sizes of the free blocks, pointers, handles, locked handles, purgeable handles, and resource handles in each heap zone.
ZoneRanger also provides windows in which a heap zone can be displayed graphically, with the size, type, and attributes of each block clearly defined. The user can control the resolution and zoom factor of this display, as well as click on any individual block to view its contents.
O V E R V I E W W I N D O W
There are two types of windows in ZoneRanger, a single Overview window and a set of Zone windows. Balloon help is available for all windows.
The Overview window is divided into seven columns, and has one row for each currently active heap zone. The first column is titled "Name" and contains the name of the process associated with the heap zone. The next three columns are titled "Free Blocks", "Pointers", and "Handles…", and contain the numbers of free blocks, pointers, and handles in the heap zone. The final three columns are titled with icons representing locked, purgeable, and resource handles, and contain the numbers of locked, purgeable, and resource handles, respectively.
Although the Overview window defaults to displaying the numbers of the different types of blocks, the user can configure whether the Overview window displays the numbers, total sizes, or percentage of these different block types in the heap zone. The user can also configure whether these figures are displayed in decimal or hexadecimal notation.
Z O N E W I N D O W
The user can open one Zone window for each heap zone that is listed in the Overview window. The zone window displays a graphic representation of the heap zone in two dimensions. Each type of block in distinguished by the pattern in which it is drawn: free blocks are drawn in white, pointers are drawn in black, and handles are drawn in gray.
Although memory is inherently one-dimensional, the second dimension of the display is achieved by wrapping the display to the width of the window. Specifically, the zone window is a two-dimensional grid in which each square represents a fixed number of bytes in the heap zone. This number of bytes is referred to as the "resolution" of the zone window, and can be configured by the user. If a given block is larger than the current resolution, then it will appear in the display as spanning the appropriate number of grid squares. If the given block is smaller than the current resolution, then it would occupy less than a single grid square, and may not appear in the display at all. Since even the smallest block must contain the 12 byte block header, one should set the resolution less than or equal to 12 bytes in order to ensure than all blocks are displayed. The default resolution for a zone window is 32 bytes.
In addition, the user can configure the pixel size of each grid square, which is referred to as the "zoom factor" of the zone window. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel squares. The default zoom factor for a zone window is 4x4.
The user can also configure whether the boundaries of each individual block are shown. In "Block View", all of the grid squares that comprise a given block are displayed as a contiguous set, and the boundaries of the block are clearly marked. In "Grid View", each grid square is drawn using the pattern representing the type of block in which it is contained, but there is no indication of where one block ends and the next one begins. The grid view of a heap zone presents less information than the block view, but can be drawn faster because it does not have to calculate and draw the block boundaries.
Finally, the user can click on any block in the heap zone to pop up information about the block and a display of its contents. If Balloon Help is enabled when the user clicks on the block, then help balloons will appear which explain information about the contents of the block in more detail.
A P P L E M E N U
ZoneRanger contains five menus: "File", "Edit", "Zones", "Configure", and "Special". It also adds menu items to the standard Apple and Help menus. Balloon help is available for all menus.
The Apple menu contains two menu items belonging to ZoneRanger, "About ZoneRanger…" and "Legend…".
The "About ZoneRanger…" menu item opens the about box for ZoneRanger.
The "Legend…" menu item opens a dialog which contains a description of which patterns are used to display each of the different block types in a zone window. This menu item is active when a Zone window is frontmost.
F I L E M E N U
The File menu contains two menu items, "Close" and "Quit".
The "Close" menu item closes the frontmost window. This menu item is active when there is a window open.
The "Quit" menu item quits the ZoneRanger application.
E D I T M E N U
The Edit menu contains the menu items for performing the required editing operations, "Undo", "Cut", "Copy", "Paste", and "Clear". None of these menu items is used by ZoneRanger; they are active only when a desk accessory is opened within the ZoneRanger application layer.
Z O N E S M E N U
The Zones menu contains the "Overview" menu item, and one menu item for each of the heap zones that is listed in the Overview window.
The "Overview" menu item will open the Overview window, or bring the window to the front if it is already open.
The remaining menu items will each open a zone window displaying the heap zone for the process for which the menu item is named, or bring the window to the front if it is already open.
C O N F I G U R E M E N U
The Configure menu contains menu items that the user can use to configure the display of the frontmost window.
The "Display Block Sizes" menu item sets the Overview window to display the total sizes of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Counts" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Counts" menu item sets the Overview window to display the total counts of the various types of blocks in each heap zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Usage". This menu item is active when the Overview window is frontmost.
The "Display Block Usage" menu item sets the Overview window to display the usage thermometer of the various types of blocks in each heap zone. A usage thermometer shows the percentage of the entire heap zone occupied by blocks of the given type. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Block Sizes" and "Display Block Counts". This menu item is active when the Overview window is frontmost.
The "Display Decimal" menu item sets the Overview window to display the sizes or counts of the various types of blocks in each heap zone in decimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Hexadecimal". This menu item is active when the Overview window is frontmost.
The "Display Hexadecimal" menu item sets the Overview window to display the sizes or counts of the various types of blocks in each heap zone in hexadecimal notation. Selecting this menu item will place a checkmark next to the item, and will deselect "Display Decimal". This menu item is active when the Overview window is frontmost.
The "Block View" menu item sets the zone window to display the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Grid View". This menu item is active when a zone window is frontmost.
The "Grid View" menu item sets the zone window to suppress the display of the boundaries of each block in the zone. Selecting this menu item will place a checkmark next to the item, and will deselect "Block View". This menu item is active when a zone window is frontmost.
The "Show Locked Handles" menu item will display all locked handles in a dark gray pattern. This menu item is active when a zone window is frontmost. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Purgeable Handles" and "Show Resource Handles". This menu item is active when a zone window is frontmost.
The "Show Purgeable Handles" menu item will display all purgeable handles in a light gray pattern. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Resource Handles". This menu item is active when a zone window is frontmost.
The "Show Resource Handles" menu item will display all resource handles in a diamond pattern. Selecting this menu item will place a checkmark next to the item, and will deselect "Show Locked Handles" and "Show Purgeable Handles". This menu item is active when a zone window is frontmost.
The "Hilite" menu item has a submenu attached, from which one can select the type of blocks to hilite in a diagonal pattern. See the "Hilite Submenu" section for a list of the menu items on the submenu. This menu item is active when a zone window is frontmost.
The "Increase Resolution" menu item increases the resolution of the display by a factor of two. It accomplishes this by halving the number of bytes represented by each grid square. The maximum allowable resolution is 1,048,576 bytes (one megabyte) per grid square. This menu item is active when a zone window is frontmost, and the resolution is not already at the maximum.
The "Decrease Resolution" menu item decreases the resolution of the display by a factor of two. It accomplishes this by doubling the number of bytes represented by each grid square. The minimum allowable resolution is 1 byte per grid square. This menu item is active when a zone window is frontmost, and the resolution is not already at the minimum.
The "Zoom In" menu item increases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a zone window is frontmost, and the zoom factor is not already at the maximum.
The "Zoom Out" menu item decreases the size of each grid square in the display. The allowable zoom factors are 1x1, 4x4, and 8x8 pixel grid squares. Furthermore, the 1x1 pixel zoom factor is not available when the display is in "Block View", since a one pixel square is not sufficiently large to draw the outline of the block. This menu item is active when a zone window is frontmost, and the zoom factor is not already at the minimum.
S P E C I A L M E N U
The Special menu contains menu items that perform a variety of specialized operations.
The "Debugger…" menu item drops the user down into the installed debugger. To return to ZoneRanger from the debugger, the user should issue the appropriate "go" command for the debugger. From MacsBug, the user should type "g" followed by a carriage return. From The Debugger from Jasik Designs, the user should select "Exit To Program" from the "Go" menu. This menu item is active when a debugger is installed, and has been tested with MacsBug amd The Debugger. It should also be active when TMON is installed.
The "Compact" menu item compacts the heap zone. The compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a zone window is frontmost.
The "Purge" menu item purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks. This menu item is active when a zone window is frontmost.
The "Compact and Purge" menu item compacts and purges the heap zone. The purging process involves changing unlocked, purgeable handles to free blocks; the compaction process involves moving unlocked handles toward the bottom of the heap, and merging together free blocks. This menu item is active when a zone window is frontmost.
The "Bring To Front" menu item bring the process associated with the heap zone to the front; that is, makes it the current application. This menu item is active when a zone window is frontmost, the process for the heap zone is not background-only, and the process is not already frontmost.
H E L P M E N U
The Help menu contains standard menu items that are used for Balloon Help, and is available on Macintoshes that are running System 7 or later.
The "About Balloon Help…" menu item opens a dialog which contains information about Balloon Help.
The "Show Balloons" menu item turns on Balloon Help. When Balloon Help is on, ZoneRanger provides help balloons for all menus, popup menus, and windows. When the menu item is selected, its name changes to "Hide Balloons". Selecting the menu item again will turn off Balloon Help.
H I L I T E S U B M E N U
The Hilite submenu contains one menu item for each different type of block that can be hilited. The hiliting is done with a diagonal pattern. Selecting any menu item will place a checkmark next to the item, and will remove the checkmark from any currently checked item on the menu. All items on this menu are active when a zone window is frontmost.
The "None" menu item turns off any existing hiliting. Selecting this menu item will not place a checkmark next to the item.
The "Free Blocks" menu item hilites all blocks in the heap zone that are free.
The "Pointers" menu item hilites all blocks in the heap zone that are pointers.
The "Handles - Unlocked, Non-Purgeable, Non-Resource" menu item hilites all blocks in the heap zone that are unlocked, non-purgeable, and do not contain a resource.
The "Handles - Locked, Non-Purgeable, Non-Resource" menu item hilites all blocks in the heap zone that are locked, non-purgeable, and do not contain a resource.
The "Handles - Unlocked, Purgeable, Non-Resource" menu item hilites all blocks in the heap zone that are unlocked, purgeable, and do not contain a resource.
The "Handles - Unlocked, Non-Purgeable, Resource" menu item hilites all blocks in the heap zone that are unlocked, non-purgeable, and contain a resource.
The "Handles - Locked, Purgeable, Non-Resource" menu item hilites all blocks in the heap zone that are locked, purgeable, and do not contain a resource.
The "Handles - Locked, Non-Purgeable, Resource" menu item hilites all blocks in the heap zone that are locked, non-purgeable, and contain a resource.
The "Handles - Unlocked, Purgeable, Resource" menu item hilites all blocks in the heap zone that are unlocked, purgeable, and contain a resource.
The "Handles - Locked, Purgeable, Resource" menu item hilites all blocks in the heap zone that are locked, purgeable, and contain a resource.
S H O R T C U T S
There are a handful of shortcuts that are available for ZoneRanger.
If Balloon Help is available, then holding down the option key when clicking the mouse in a menu will turn on the help balloons until the mouse button is released. Similarly, holding down the option key when opening a popup menu will turn on the help balloons until the mouse button is released. This is a useful way to quickly receive help for a menu item or items without explicitly turning Balloon Help on and off manually.
Holding down the command key will turn on the "Display Block Sizes" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the option key will turn on the "Display Block Counts" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
Holding down the control key will turn on the "Display Block Usage" menu item as long as the key remains depressed. This shortcut works whether ZoneRanger is in the foreground or the background. This is a useful way to toggle between display modes temporarily, without having to bring ZoneRanger to the foreground or go to the Configure menu.
S Y S T E M R E Q U I R E M E N T S
ZoneRanger requires System 7 or later with 32-bit addressing enabled. A future version of ZoneRanger should eliminate the need for both of these requirements.
K N O W N L I M I T A T I O N S
There are currently a handful of known limitations to ZoneRanger. A future version of ZoneRanger should eliminate all of these limitations.
System 7 or later is required.
32-bit addressing must be enabled.
ZoneRanger makes every attempt to operate smoothly under low-memory conditions; the Macintosh Toolbox, however, does not. As such, if the application runs out of memory during a toolbox call, ZoneRanger will return to the Finder any warning to the user. Since the application is already out of memory, the trick is to determine how to inform the user of what has happened without allocating any memory.
When the user quits ZoneRanger, the application will not save the configuration settings and window locations.
ZoneRanger uses a single offscreen drawing world for all open windows, which is sized to accomodate the largest of the windows. When the largest window is closed, the offscreen world is not reduced appropriately. This efficiency would regain a certain amount of memory.
K N O W N B U G S
There are currently a handful of known bugs in ZoneRanger. A future version of ZoneRanger should address all of these.
When the user sizes a zone window or changes its resolution or zoom factor, the window will scroll back to the top.
When a zone window for ZoneRanger itself is open, it is possible to pop up a display of the single free block out of which the toolbox will allocate the memory it needs to pop up the block. Between the time that the user clicks on this special free block and the block is popped up, a portion of the block has been allocated and is no longer free. As such, random data will appear in the popup. This bug only occurs in a zone window for ZoneRanger itself, and only for a single free block within this window.
ZoneRanger is free; it may be freely copied and distributed, provided that this copyright notice is preserved on all copies. The software may not, however, be sold or distributed for profit, or included with other software which is sold or distributed for profit, without the permission of the author.
S O U R C E C O D E
The source code for the program can be purchased for $20, and is available from the author at the address below.
S P E C I A L T H A N K S
All of the source code for ZoneRanger was written by the author. One must thank, however, Eric Hanig and Mike Engber for the numerous suggestions they have made regarding the feature set and user interface.
C O M M E N T S A N D S U G G E S T I O N S
Any comments and suggestions are welcome, and can be sent to the address below.
